home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / mail / atpdos06.zip / EDITLINE.DOC < prev    next >
Text File  |  1992-12-04  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. EDITLINE(3)                                           EDITLINE(3)
  5.  
  6.  
  7. NAME
  8.        editline - command-line editing library with history
  9.  
  10. SYNOPSIS
  11.        char *
  12.        readline(prompt)
  13.             char *prompt;
  14.  
  15.        void
  16.        add_history(line)
  17.            char  *line;
  18.  
  19. DESCRIPTION
  20.        Editline is a library that provides an line-editing inter-
  21.        face with text recall.  It is intended  to  be  compatible
  22.        with  the  readline  library provided by the Free Software
  23.        Foundation, but much smaller.  The  bulk  of  this  manual
  24.        page describes the user interface.
  25.  
  26.        The  readline  routine  returns  a  line  of text with the
  27.        trailing newline removed.   The  data  is  returned  in  a
  28.        buffer  allocated  with  malloc(3), so the space should be
  29.        released with free(3) when the  calling  program  is  done
  30.        with it.  Before accepting input from the user, the speci-
  31.        fied prompt is displayed on the terminal.
  32.  
  33.        The add_history routine makes a copy of the specified line
  34.        and adds it to the internal history list.
  35.  
  36.    User Interface
  37.        A  program that uses this library provides a simple emacs-
  38.        like editing interface to its users.  A line may be edited
  39.        before  it is sent to the calling program by typing either
  40.        control characters or escape sequences.  A control charac-
  41.        ter,  shown  as  a caret followed by a letter, is typed by
  42.        holding down the  ``control''  key  while  the  letter  is
  43.        typed.   For  example,  ``^A''  is a control-A.  An escape
  44.        sequence is entered by typing the ``escape'' key  followed
  45.        by  one or more characters.  The escape key is abbreviated
  46.        as ``ESC.''  Note that unlike control keys,  case  matters
  47.        in   escape  sequences;  ``ESC F''  is  not  the  same  as
  48.        ``ESC f''.
  49.  
  50.        An editing command may be typed anywhere on the line,  not
  51.        just  at the beginning.  In addition, a return may also be
  52.        typed anywhere on the line, not just at the end.
  53.  
  54.        Most editing commands may be  given  a  repeat  count,  n,
  55.        where  n  is  a number.  To enter a repeat count, type the
  56.        escape key, the number, and then the command  to  execute.
  57.        For  example,  ``ESC 4 ^f'' moves forward four characters.
  58.        If a command may be given a repeat  count  then  the  text
  59.        ``[n]'' is given at the end of its description.
  60.  
  61.  
  62.  
  63.  
  64.                                                                 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. EDITLINE(3)                                           EDITLINE(3)
  71.  
  72.  
  73.        The following control characters are accepted:
  74.               ^A       Move to the beginning of the line
  75.               ^B       Move left (backwards) [n]
  76.               ^D       Delete character [n]
  77.               ^E       Move to end of line
  78.               ^F       Move right (forwards) [n]
  79.               ^G       Ring the bell
  80.               ^H       Delete character before cursor (backspace key) [n]
  81.               ^I       Complete filename (tab key); see below
  82.               ^J       Done with line (return key)
  83.               ^K       Kill to end of line (or column [n])
  84.               ^L       Redisplay line
  85.               ^M       Done with line (alternate return key)
  86.               ^N       Get next line from history [n]
  87.               ^P       Get previous line from history [n]
  88.               ^R       Search backward (forward if [n]) through history for
  89.                        text; must start line if text begins with an uparrow
  90.               ^T       Transpose characters
  91.               ^V       Insert next character, even if it is an edit command
  92.               ^W       Wipe to the mark
  93.               ^X^X     Exchange current location and mark
  94.               ^Y       Yank back last killed text
  95.               ^[       Start an escape sequence (escape key)
  96.               ^]c      Move forward to next character ``c''
  97.               ^?       Delete character before cursor (delete key) [n]
  98.  
  99.        The following escape sequences are provided.
  100.               ESC ^H   Delete previous word (backspace key) [n]
  101.               ESC DEL  Delete previous word (delete key) [n]
  102.               ESC SP   Set the mark (space key); see ^X^X and ^Y above
  103.               ESC .    Get the last (or [n]'th) word from previous line
  104.               ESC ?    Show possible completions; see below
  105.               ESC <    Move to start of history
  106.               ESC >    Move to end of history
  107.               ESC b    Move backward a word [n]
  108.               ESC d    Delete word under cursor [n]
  109.               ESC f    Move forward a word [n]
  110.               ESC l    Make word lowercase [n]
  111.               ESC u    Make word uppercase [n]
  112.               ESC y    Yank back last killed text
  113.               ESC v    Show library version
  114.               ESC w    Make area up to mark yankable
  115.               ESC nn   Set repeat count to the number nn
  116.               ESC C    Read from environment variable ``_C_'', where C is
  117.                        an uppercase letter
  118.  
  119.        The  editline  library has a small macro facility.  If you
  120.        type the escape key followed by an  uppercase  letter,  C,
  121.        then the contents of the environment variable _C_ are read
  122.        in as if you had typed them at the keyboard.  For example,
  123.        if the variable _L_ contains the following:
  124.               ^A^Kecho '^V^[[H^V^[[2J'^M
  125.        Then  typing  ``ESC  L'' will move to the beginning of the
  126.        line, kill the entire line, enter the echo command  needed
  127.  
  128.  
  129.  
  130.                                                                 2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. EDITLINE(3)                                           EDITLINE(3)
  137.  
  138.  
  139.        to clear the terminal (if your terminal is like a VT-100),
  140.        and send the line back to the shell.
  141.  
  142.        The editline library also does filename completion.   Sup-
  143.        pose the root directory has the following files in it:
  144.               bin    vmunix
  145.               core   vmunix.old
  146.        If you type ``rm /v'' and then the tab key.  Editline will
  147.        then finish off as much of the name as possible by  adding
  148.        ``munix''.   Because  the name is not unique, it will then
  149.        beep.  If you type the escape key and a question mark,  it
  150.        will  display  the two choices.  If you then type a period
  151.        and a tab, the library will finish off  the  filename  for
  152.        you:
  153.               rm /v[TAB]munix.TABold
  154.        The  tab  key is shown by ``[TAB]'' and the automatically-
  155.        entered text is shown in italics.
  156.  
  157. BUGS AND LIMITATIONS
  158.        Cannot handle lines more than 80 columns.
  159.  
  160. AUTHORS
  161.        Simmule R. Turner  <uunet.uu.net!capitol!sysgo!simmy>  and
  162.        Rich  $alz <rsalz@osf.org>.  Original manual page by DaviD
  163.        W. Sanderson <dws@ssec.wisc.edu>.
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                                                                 3
  197.  
  198.  
  199.